<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Language Versions</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../quickbook.html" title="Chapter&#160;39.&#160;Quickbook 1.5">
<link rel="prev" href="syntax/block.html" title="Block Level Elements">
<link rel="next" href="install.html" title="Installation and configuration">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="syntax/block.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="install.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="quickbook.versions"></a>Language Versions</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="versions.html#quickbook.versions.stable">Stable Versions</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6">Quickbook 1.6</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_7">Quickbook 1.7</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.versions.stable"></a><a class="link" href="versions.html#quickbook.versions.stable" title="Stable Versions">Stable Versions</a>
</h3></div></div></div>
<p>
        Since quickbook 1.3 the <code class="computeroutput">quickbook</code> attribute in the document
        block selects which version of the language to use. Not all changes to quickbook
        are implemented using a version switch, it's mainly just the changes that
        change the way a document is interpreted or would break existing documentation.
      </p>
<h4>
<a name="quickbook.versions.stable.h0"></a>
        <span><a name="quickbook.versions.stable.quickbook_1_3_and_later"></a></span><a class="link" href="versions.html#quickbook.versions.stable.quickbook_1_3_and_later">Quickbook
        1.3 and later</a>
      </h4>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
            Introduced quickbook language versioning.
          </li>
<li class="listitem">
            In the documentation info, allow phrase markup in license and purpose
            attributes.
          </li>
<li class="listitem">
            Fully qualified section and headers. Subsection names are concatenated
            to the ID to avoid clashing. Example: <code class="computeroutput">doc_name.sect_name.sub_sect_name.sub_sub_sect_name</code>.
          </li>
</ul></div>
<h4>
<a name="quickbook.versions.stable.h1"></a>
        <span><a name="quickbook.versions.stable.quickbook_1_5_and_later"></a></span><a class="link" href="versions.html#quickbook.versions.stable.quickbook_1_5_and_later">Quickbook
        1.5 and later</a>
      </h4>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
            Ignore template argument separators inside square brackets.
          </li>
<li class="listitem">
            Don't separate the final template argument if the <code class="computeroutput">..</code> separator
            was used. i.e. never mix <code class="computeroutput">..</code> and whitespace separators.
          </li>
<li class="listitem">
            Statically scope templates and their arguments rather than dynamically
            scope them.
          </li>
<li class="listitem">
            Give table ids, and let you set them.
          </li>
<li class="listitem">
            Allow spaces between the <code class="computeroutput">:</code> character and ids in elements
            which can have ids.
          </li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.versions.1_6"></a><a class="link" href="versions.html#quickbook.versions.1_6" title="Quickbook 1.6">Quickbook 1.6</a>
</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.docinfo">Includes with docinfo</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.scope">Scoping templates and
        macros</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.include">Including C++ and python
        files</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.ids">Id Generation</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.compatibility">Compatibility
        Mode</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.version">Version info outside
        of document info block</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.heading_ids">Explicit Heading
        Ids</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.escapes">Punctuation changes</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.table">Table Titles</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.xmlbase">XML base</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.elements">New Elements</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_6.listparagraphs">Pargraphs in
        lists</a></span></dt>
</dl></div>
<p>
        Everything described in here may change depending on the feedback received.
      </p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.docinfo"></a><a class="link" href="versions.html#quickbook.versions.1_6.docinfo" title="Includes with docinfo">Includes with docinfo</a>
</h4></div></div></div>
<p>
          In quickbook 1.5 if you include a file which starts with a docinfo block,
          it's ignored and the file is expanded in place. In quickbook 1.6 it's treated
          as a document nested in the current position. So if it has an 'article'
          docinfo block, boostbook 'article' tags are used.
        </p>
<p>
          It also mostly generates the same markup as if the file was converted separately
          - so for example, the same ids are generated, the document is processed
          using the language version specified in the docinfo block. If no language
          is specified it uses the default (1.1) not the version of the document
          that included it. This might seem surprising, but is requried so that quickbook
          will convert it the same way as if it was converted separately.
        </p>
<p>
          So for the most part, includes with a docinfo are like an <code class="computeroutput">xinclude</code>,
          apart from a couple of differences. Templates and macros defined in the
          parent document are used in the included document, and the id generator
          rewrites ids that clash between multiple documents.
        </p>
<p>
          If an included document doesn't have a docinfo block, it's just included
          as before.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.scope"></a><a class="link" href="versions.html#quickbook.versions.1_6.scope" title="Scoping templates and macros">Scoping templates and
        macros</a>
</h4></div></div></div>
<p>
          A long standing quickbook bug is that macros are scoped by file, but templates
          aren't. So you can define templates in a separate file and include them,
          but not macros. This has been fixed so that templates defined in one file
          won't 'leak' into another.
        </p>
<p>
          But this means there's no way to define templates in a separate file -
          a useful feature. To do this the <code class="computeroutput">import</code> element has been adapted
          to also support quickbook files. If a quickbook file is imported, the templates
          and macros defined in it are added to the current scope, but nothing else
          contained in that file is used. This could be used to create template and
          macro library files. This matches the existing semantics of importing code
          snippets.
        </p>
<p>
          When importing templates, they're bound to the language version of the
          file they were defined in. This means that if you import them into a file
          with a different version it won't change the way they're interpreted. Although,
          as we'll see <a class="link" href="versions.html#compatibility">later</a>, the generated
          boostbook is slightly different.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.include"></a><a class="link" href="versions.html#quickbook.versions.1_6.include" title="Including C++ and python files">Including C++ and python
        files</a>
</h4></div></div></div>
<p>
          As <code class="computeroutput">import</code> now supports quickbook files, <code class="computeroutput">include</code>
          also supports source files. It includes any quickbook contained in comments
          outside of code snippets. Code snippets in the file are available to be
          expanded within the file but are scoped to the file. In exactly the same
          manner as when templates and macros are scoped in an included quickbook
          file.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.ids"></a><a class="link" href="versions.html#quickbook.versions.1_6.ids" title="Id Generation">Id Generation</a>
</h4></div></div></div>
<p>
          Id generation in quickbook 1.5 is a bit buggy, but that can't be fixed
          without a version switch as it will break existing documents. For example
          in quickbook 1.5 when you include a quickbook file, it stops using the
          explicit id from the documentation info and generates a new id from the
          document title to use instead.
        </p>
<p>
          The id generator in quickbook 1.6 has been improved in some other ways
          to. When generating ids from section titles, table titles etc. it always
          uses the quickbook source rather than the generated boostbook to generate
          the id. It then cleans up the id slightly, trimming leading and trailing
          underscores and replacing multiple underscores with a single underscore.
          Then if the newly generated part of the id is longer than 32 characters
          it truncates it.
        </p>
<p>
          While the new id generator generally creates better ids, it's more likely
          to generate duplicates so quickbook needs to handle duplicates better.
          When there are multiple identical ids, quickbook chooses one to use based
          on a priority list - anchors are preferred, then explicit document and
          section ids, then other explicit ids, followed by the generated ids. Then
          any other explicit ids in the document have numbers added to avoid duplicates
          - first the explicit ids in the order they appear and then the generated
          ids. A generated id which accidentally clashes with an explicit id should
          never change the explicit id.
        </p>
<p>
          Older language versions still generate the same ids they always have, with
          the exception of duplicate ids which are handled using the new mechanism
          - this is not a breaking change since duplicate ids can't be linked to.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.compatibility"></a><a name="compatibility"></a><a class="link" href="versions.html#quickbook.versions.1_6.compatibility" title="Compatibility Mode">Compatibility
        Mode</a>
</h4></div></div></div>
<p>
          As mentioned before, changing the id generator will break links in documents
          written using an old language version. So to ease the transition a 'compatibility
          mode' is used, this just requires an extra attribute in the docinfo, for
          example if you're converting a 1.5 document to 1.6:
        </p>
<pre class="programlisting">[article Document
[quickbook 1.6]
[compatibility-mode 1.5]
]
</pre>
<p>
          This means the document will be parsed as 1.6, using all the new features,
          but ids (and possibly other markup) will generated as they were for a 1.5
          document.
        </p>
<p>
          Compatibility mode is also implicitly used when generating templates written
          in a different language version to the current document. So the template
          is parsed in the version it was written for, but generates boostbook that's
          compatible with the current document.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.version"></a><a class="link" href="versions.html#quickbook.versions.1_6.version" title="Version info outside of document info block">Version info outside
        of document info block</a>
</h4></div></div></div>
<p>
          Can now use <code class="computeroutput">quickbook</code> and <code class="computeroutput">compatibility-mode</code>
          tags at the beginning of the file. Either before or without a document
          info block. This is useful for files just containing templates, which don't
          really need a document info block.
        </p>
<p>
          If you don't specify <code class="computeroutput">compatibility-mode</code>, the behaviour depends
          on whether or not you have a docinfo block. If you do it uses the file's
          quickbook version, if you don't it inherits the parent's compatibility
          mode even if you specify a quickbook version. This is the right thing to
          do - mixing compatibility modes within documents is problematic. It might
          actually be a mistake to allow them to specified outside docinfo blocks.
        </p>
<p>
          This change is also backdated to older versions. So when including from
          an older version, the included file's version can be set (older versions
          ignore document info in included files).
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.heading_ids"></a><a class="link" href="versions.html#quickbook.versions.1_6.heading_ids" title="Explicit Heading Ids">Explicit Heading
        Ids</a>
</h4></div></div></div>
<p>
          Headings can now be given explicit ids:
        </p>
<pre class="programlisting">[heading:id A heading with an explicit id]
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.escapes"></a><a class="link" href="versions.html#quickbook.versions.1_6.escapes" title="Punctuation changes">Punctuation changes</a>
</h4></div></div></div>
<p>
          In 1.6, quickbook is more consistent about how it parses punctuation. Escapes
          are now supported in links, anchors, table titles, image attributes etc.
          The flip side of this is that quickbook is now stricter about unescaped
          brackets. They can still be used, but need to match up, otherwise there's
          an error.
        </p>
<p>
          Since quickbook now matches up square brackets it will fix some mis-parses.
          For example <code class="computeroutput">[*[bold]]</code> used to parse as <span class="bold"><strong>[bold</strong></span>]
          - note that the closing square bracket isn't bold, now it parses as <span class="bold"><strong>[bold]</strong></span>. In this case it's just a subtle visual difference,
          but it could cause odd problems, for example when nested in a table cell.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.table"></a><a class="link" href="versions.html#quickbook.versions.1_6.table" title="Table Titles">Table Titles</a>
</h4></div></div></div>
<p>
          Table titles are now parsed as phrases, so some markup is allowd:
        </p>
<pre class="programlisting">[table [*bold title]]
</pre>
<p>
          Which is an empty table with a bold title. The title is no longer ended
          by a newline, but by either a closing square bracket, or two opening square
          brackets - which you get at the start of the table cells, so this now works:
        </p>
<pre class="programlisting">[table Simple[[heading 1][heading 2]][[cell 1][cell 2]]]
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.xmlbase"></a><a class="link" href="versions.html#quickbook.versions.1_6.xmlbase" title="XML base">XML base</a>
</h4></div></div></div>
<p>
          A problem when using <code class="computeroutput">xi:include</code> tags in escaped boostbook
          is that you typically don't know which directory the boostbook file will
          be in, so it's impossible to use relative links. This can be fixed by adding
          an <code class="computeroutput">xml:base</code> attribute to the document tag. To do this use
          the new <code class="computeroutput">xmlbase</code> attribute in your document's docinfo block.
          For example to make escaped <code class="computeroutput">xi:include</code>s be relative to the
          directory of the file:
        </p>
<pre class="programlisting">[library Library documentation
[quickbook 1.6]
[xmlbase .]
]
</pre>
<p>
          Any paths in <code class="computeroutput">xinclude</code> elements will be rewritten accordingly.
          Note that most documents won't need this, and probably shouldn't use it.
          Only use it if you're totally sure that you will need it.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.elements"></a><a class="link" href="versions.html#quickbook.versions.1_6.elements" title="New Elements">New Elements</a>
</h4></div></div></div>
<p>
          New elements in 1.6 (to be documented later):
        </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
              <code class="computeroutput">block</code>
            </li>
<li class="listitem">
              <code class="computeroutput">ordered_list</code>
            </li>
<li class="listitem">
              <code class="computeroutput">itemized_list</code>
            </li>
<li class="listitem">
              <code class="computeroutput">role</code>
            </li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_6.listparagraphs"></a><a class="link" href="versions.html#quickbook.versions.1_6.listparagraphs" title="Pargraphs in lists">Pargraphs in
        lists</a>
</h4></div></div></div>
<p>
          I'm still refining this, but paragraphs and block elements can now be used
          in lists:
        </p>
<pre class="programlisting">* Para 1

  Para 2
  * Nested Para 1

    Nested Para 2

        Code block
  Para 3
</pre>
<p>
          generates:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
              Para 1
              <p>
                Para 2
              </p>
              <div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem">
                    Nested Para 1
                    <p>
                      Nested Para 2
                    </p>
<pre class="programlisting">Code block
</pre>
                  </li></ul></div>
              <p>
                Para 3
              </p>
            </li></ul></div>
<p>
          The docbook markup that this generates is pretty bad, but seems to create
          okay html.
        </p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.versions.1_7"></a><a class="link" href="versions.html#quickbook.versions.1_7" title="Quickbook 1.7">Quickbook 1.7</a>
</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_7.source_mode">Source mode for
        single entities</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_7.callouts">Callouts in code block</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_7.escaped_docinfo_attributes">Escaped
        docbook in docinfo blocks</a></span></dt>
<dt><span class="section"><a href="versions.html#quickbook.versions.1_7.templates_in_link_values">Templates
        in link values</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_7.source_mode"></a><a class="link" href="versions.html#quickbook.versions.1_7.source_mode" title="Source mode for single entities">Source mode for
        single entities</a>
</h4></div></div></div>
<p>
          1.7 introduces a new <code class="computeroutput">!</code> element type for setting the source
          mode of a single entity without changing the source mode otherwise. This
          can be used for code blocks and other elements. For example:
        </p>
<pre class="programlisting">[!c++]
    void foo() {};

[!python]```def foo():```
</pre>
<p>
          It can also be used to set the source mode for elements:
        </p>
<pre class="programlisting">[!teletype][table
    [[code][meaning]]
    [[`+`][addition]]
]
</pre>
<p>
          When used a section, it's only set for the section element, not the whole
          section.
        </p>
<p>
          Currently it does support other syntactic entities such as paragraphs and
          lists. I'm not sure if it would be a good idea.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_7.callouts"></a><a class="link" href="versions.html#quickbook.versions.1_7.callouts" title="Callouts in code block">Callouts in code block</a>
</h4></div></div></div>
<p>
          Currently callouts can only be used in code snippets. 1.7 add support in
          normal code blocks. The same syntax is used as in code snippets, the callout
          descriptions appear immediately after the code block.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_7.escaped_docinfo_attributes"></a><a class="link" href="versions.html#quickbook.versions.1_7.escaped_docinfo_attributes" title="Escaped docbook in docinfo blocks">Escaped
        docbook in docinfo blocks</a>
</h4></div></div></div>
<p>
          Quickbook docinfo attributes will probably never be as rich as docbook
          attributes so to allow more flexible markup, not supported by quickbook
          escaped docbook can be included in the docinfo block:
        </p>
<pre class="programlisting">[article Some article
[quickbook 1.7]
'''&lt;author&gt;
    &lt;firstname&gt;John&lt;/firstname&gt;
    &lt;surname&gt;Doe&lt;/surname&gt;
    &lt;email&gt;john.doe@example.com&lt;/email&gt;
&lt;/author&gt;'''
]
</pre>
<p>
          The escaped docbook is always placed at the end of the docinfo block, so
          it shouldn't be assumed that it will interleave the markup. A mixture of
          quickbook and docbook attributes for the same information will not work
          well.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.versions.1_7.templates_in_link_values"></a><a class="link" href="versions.html#quickbook.versions.1_7.templates_in_link_values" title="Templates in link values">Templates
        in link values</a>
</h4></div></div></div>
<p>
          There's very premilinary support for calling templates in link values.
          A lot more work needs to be done, including:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
              Considering other places where templates could be called (e.g. images
              are quite tricky, as templates could get confused with attributes,
              should templates be callable from something like an element's id?).
            </li>
<li class="listitem">
              Trimming spaces from the body of the template (which can cause surprising
              results).
            </li>
<li class="listitem">
              Checking that the contents of the template are appropriate for the
              context. Possibly even using a different grammar.
            </li>
</ul></div>
</div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2002, 2004, 2006 Joel de Guzman,
      Eric Niebler<br>Copyright &#169; 2010, 2011 Daniel James<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="syntax/block.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="install.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
